---
description: Обязательный компонент, в который нужно обернуть всё приложение.
  В нём инкапсулирована логика режимов встраивания, управления прокруткой, безопасными отступами и порталами.
---

<Overview group="configuration">

# AppRoot [tag:component]

[Обязательный компонент](/overview/install#step4), в который нужно обернуть всё приложение. В нём инкапсулирована логика:

- режимов встраивания,
- управления прокруткой,
- безопасными отступами,
- и порталами.

</Overview>

## Режимы встраивания

Задаётся свойством `mode`.

- `"full"` — ваше приложение полностью реализовано с помощью VKUI;
- `"embedded"` — ваше приложение реализовано в виде блока, встроенного в основное приложение
  (например, Марусю или базовое приложение ВКонтакте);
- `"partial"` — ваше приложение реализовано с помощью сторонних решений и использует некоторые компоненты библиотеки VKUI.

В чём главные особенности перечисленных режимов и какой режим выбрать?

### Full

Этот режим используется по умолчанию и позволяет VKUI полностью контролировать страницы вашего приложения.
Предполагается, что `root`-элемент (точка монтирования приложения) приложения находится непосредственно внутри `<body>`.
VKUI добавит свои классы на `html`-элемент и на `root`-элемент.
Рекомендуем использовать его для `standalone`-проектов или при [интеграции с платформой VK Mini Apps](/integrations/vk-mini-apps).

### Embedded

Данный режим позволяет вам подключить VKUI не на всю страницу приложения, а только к определенному контейнеру.
В отличие от `full` режима, VKUI добавит свои классы только на корневой контейнер (`.vkui__root` и `.vkui__root--embedded`).

По умолчанию, в режиме `embedded` система координат элементов с `position: fixed` переносится на свой контейнер через `transform: translate3d(0, 0, 0)`.
Это поведение можно отключить с помощью свойства `disableParentTransformForPositionFixedElements`.

### Partial

Данный режим подходит для случаев, когда вам нужно сверстать небольшой блок, а не страницу целиком. В `partial` режиме не подразумевается использование компонентов из раздела `Layout`. VKUI не добавляет никаких классов на `html` или корневой элемент.

## Визуальное оформление

Свойство `layout` глобально задаёт тип оформления макета для компонентов [`Panel`](/components/panel) и [`Group`](/components/group).

- `"card"` — карточный дизайн с тенями и скруглениями;
- `"plain"` — плоский дизайн без теней и скруглений.

## Управление порталами

VKUI использует [порталы](https://react.dev/reference/react-dom/createPortal) для рендеринга всплывающих элементов (модальные окна, тултипы и т.д.).
По умолчанию, они рендерятся в `document.body`.

С помощью свойства `portalRoot` можно переопределить элемент, в котором будут рендериться всплывающие элементы.
Можно указать конкретный `DOM`-элемент (полученный, например, через `document.getElementById`) или ссылку на `DOM`-элемент (`ref`-объект).

С помощью свойства `disablePortal` можно отключить рендер всплывающих элементов в отдельном контейнере -
они будут рендериться непосредственно по месту определения.

## Управление полосой прокрутки

Задаётся свойством `scroll`.

- `"global"` — VKUI-приложение скроллится вместе со страницей;
- `"contain"` — VKUI-приложение живет в отдельной зоне и скроллится независимо внутри `AppRoot` (например, в модалке).

В режимах `full` и `embedded` VKUI управляет полосой прокрутки приложения - например, блокирует скролл при поднятии
модального окна или запоминает положение скролла при переходе между панелями (`Panel`).

В случае `scroll="global"` положение полосы прокрутки рассчитывается относительно глобальных `window/document` страницы.
В случае `scroll="contain"` положение полосы прокрутки рассчитывается относительно выбранного корневого элемента,
это может быть полезно при использовании `mode="embedded"`.

## Безопасные отступы (safe-area-inset-\*) [#safe-area-insets]

Задаётся свойством `safeAreaInsets`.

Иногда приложению может быть доступна не вся область экрана (например, смартфоны с "чёлкой").
Чтобы части приложения не перекрывали нативные элементы, мы используем стандартные `safe-area-inset-*`.
Подробнее можно ознакомиться в [документации](https://developer.mozilla.org/en-US/docs/Web/CSS/env#safe-area-inset-top).

Если вы разрабатываете мини-приложение или встраиваетесь в интерфейс, который требует использования специфичных отступов, то
используйте свойство `safeAreaInsets`, которое позволяет переопределять значения по умолчанию:

```jsx
const customSafeAreaInsets = {
  top?: number;
  right?: number;
  bottom?: number;
  left?: number;
}

// Переопределяем стандартные отступы
<AppRoot safeAreaInsets={customSafeAreaInsets}>
  <App />
</AppRoot>
```

Вы можете переопределить только часть отступов (например, только `bottom` или `top`), остальные значения будут использовать
заданные по умолчанию отступы.

## Выделение текста

Задаётся свойством `userSelectMode`.

Поскольку VKUI мимикрирует под мобильные платформы, мы по умолчанию запрещаем выделять текст в приложениях, запущенных в `webview`.
Для более гибкой настройки поведения используйте следующие значения:

- `"enabled-with-pointer"` – разрешается выделять текст, если устройство ввода типа `pointer` (например, мышь), в остальных случаях запрещается;
- `"disabled"` – запрещается выделять текст;
- `"enabled"` – разрешается выделять текст.

## Свойства и методы [#api]

<PropsTable name="AppRoot" />
